Skip to content

DirectXTK

Jump to bottom
Chuck Walbourn edited this page Mar 27, 2024 · 140 revisions

Headers

Public headers are in the Inc folder of the distribution package.

Namespace

All the functions in the library are in the DirectX C++ namespace.

using namespace DirectX;

The Xbox One exclusive application XBoxDDSTextureLoader functions are in the Xbox C++ namespace.

Modules

Tools

  • MakeSpriteFont - builds .spritefont data files for use with SpriteFont class
  • XWBTool - builds .xwb XACT-style wave banks for use with WaveBank class

Building

This code is designed to build with Visual Studio 2019 or later. It requires the Windows SDK (19041) or later for functionality such as the DirectXMath library and the DXGI 1.2 headers.

These components are designed to work without requiring any content from the DirectX SDK. For details, see Where is the DirectX SDK?, Where is the DirectX SDK (2021 Edition)?, and The Zombie DirectX SDK.

HLSL shaders

The required Direct3D shaders are built as headers in Src\Shader\Compiled\*.inc and included into the DirectXTK static library. They are automatically built by the Visual Studio project if they are not present, and cleared by a Clean. They can also be manually rebuilt using the CompileShaders.cmd script (i.e. ...\DirectXTK\Src\Shaders)

Adding to a VS solution

Using project-to-project references

In your application's solution, right-click on the Solution and use Add \ Existing Project... to add the appropriate .vcxproj file to your solution.

DirectXTK_Desktop_2022 Windows desktop applications for Windows 7 Service Pack 1 or later building with VS 2022 Community, Professional or higher with the latest installed Windows SDK.
DirectXTK_Desktop_2022_Win10 Windows desktop applications for Windows 10 building with VS 2022 Community, Professional or higher with the latest installed Windows SDK. Uses XAudio 2.9 and Windows.Gaming.Input
DirectXTK_Windows10_2022 Universal Windows Platform (UWP) apps building with VS 2022 with the latest installed Windows SDK.
DirectXTK_GDK_2022 Windows 10 games building with VS 2022 using the Microsoft GDK.
DirectXTK_Desktop_2019 Windows desktop applications for Windows 7 Service Pack 1 or later building with VS 2019 Community, Professional or higher with the latest installed Windows SDK.
DirectXTK_Desktop_2019_Win10 Windows desktop applications for Windows 10 building with VS 2019 Community, Professional or higher with the latest installed Windows SDK. Uses XAudio 2.9 and Windows.Gaming.Input
DirectXTK_GDK_2019 Windows 10 games building with VS 2019 using the Microsoft GDK.

For VS 2019, use of the 16.11 is required as all previous versions are no longer supported.

In your application's project, right-click on the Project and use "References...", then "Add New Reference...", and then check the DirectXTK project name and click OK. For a Universal Windows Platform (UWP) app or Xbox One solution, you may need to set Reference Assembly Output to false since DirectXTK is a static C++ library and not a WinRT component.

Settings dialog

In your application's project settings, on the "C++ / General" page set Configuration to "All Configurations", set Platform to "All Platforms", and then add the relative path to DirectXTK\inc;--assuming you have the DirectXTK folder in the same directory as your sln file, it should be $(SolutionDir)\DirectXTK\inc;--to the Additional Include Directories properties. Click Apply.

Settings dialog

See Audio for additional information when setting up Windows desktop projects to use DirectXTK for Audio.

See also the Visual C+ Team Blog

Using NuGet package manager

Alternatively you can use NuGet to install one of the DirectX Tool Kit packages. Use Project / Manage NuGet Packages... then select "Online" and search for "DirectXTK".

directxtk_desktop_2019 This NuGet is configured for Windows desktop C++ applications building with VS 2019 or VS 2022 Community/Professional or higher. DirectXTK for Audio in this package uses XAudio2Redist to support Windows 7 or later.
directxtk_desktop_win10 This NuGet is configured for Windows desktop C++ applications building for Windows 10 with VS 2019 or VS 2022 Community/Professional or higher. DirectXTK for Audio in this package uses XAudio 2.9 in the Windows SDK.
directxtk_uwp This NuGet is configured for Universal Windows Platform apps for Windows 10 building with VS 2019 or VS 2022 Community/Professional or higher. DirectXTK for Audio in this package uses XAudio 2.9 in the Windows SDK.

You should use the NuGet interface to check for updates if you have an older version installed.

Archived

These NuGet packages are no longer supported.

Using the vcpkg C++ library manager

The DirectX Tool Kit is also available through the vcpkg C++ Library Manager.

vcpkg install directxtk

For the 64-bit version of the library, use:

vcpkg install directxtk:x64-windows

For the Universal Windows Platform (UWP) versions, use:

vcpkg install directxtk:x64-uwp

arm, arm64, x86, x64, windows, windows-static, windows-static-md, and uwp triplets are supported.

Windows Subsystem for Linux (i.e. arm64-linux and x64-linux) is not supported.

The vcpkg port supports five optional features. The default is to build without DirectX Tool Kit for Audio support except UWP which always includes it.

  • tools: Installs MakeSpriteFont and xwbtool command-line tools
  • spectre: Builds the library with Spectre-mitigation enabled
  • xaudio2-8 Use XAudio 2.8 for Windows 8.x or later support
  • xaudio2-9 Use XAudio 2.9 for Windows 10/Windows 11
  • xaudio2redist Use the XAudio2Redist for Windows 7 SP1 or later support

CMake

You can reference the DirectX Tool Kit CMake package using:

find_package(directxtk CONFIG REQUIRED)

target_link_libraries(foo Microsoft::DirectXTK)

If using vcpkg C++ Package Manager, then you add the CMAKE_TOOLCHAIN_FILE path to vcpkg\scripts\buildsystems\vcpkg.cmake. If not using vcpkg, you need to provide a per-configuration path to the installed location in the directxtk_DIR variable. Otherwise the find_package will fail.

vcpkg toolchain setting

There are also CMakePresets.json files available for the CMake projects on directx-vs-templates that use the VCPKG_ROOT environment variable to locate the VCPKG install directory. See the commented out code in CMakeLists.txt as well.

Dependencies

The DirectX Tool Kit library assumes your binary is linking with the following system libraries:

  • d3d11.lib: Provides the Direct3D device creation function D3D11CreateDevice
  • dxgi.lib: Provides the DXGI factory creation function CreateDXGIFactory1 / CreateDXGIFactory2
  • dxguid.lib: Provides COM GUID values for IID_ID3D11Device, WKPDID_D3DDebugObjectName, etc.
  • windowscodecs.lib or uuid.lib: Provides COM GUID values for WIC usage such as CLSID_WICImagingFactory, CLSID_WICImagingFactory1, CLSID_WICImagingFactory2, etc.
  • For Win32 desktop applications, ole32.lib: Provides CoCreateInstance. For other platforms, this export is in the umbrella library (WindowsApps.lib, onecore.lib, etc.).

DirectX Tool Kit for Audio

For "Windows 8.x" or "Windows 10" configurations of the AudioEngine class, you'll need to use xaudio2.lib.

For XAudio2Redist, the Microsoft.XAudio2.Redist NuGet package provides the xaudio2_9redist.lib.

GamePad

For "Windows 10" configurations of the GamePad class that use Windows.Gaming.Input, you need runtimeobject.lib for Win32 desktop apps. For UWP apps, this is already handled with the umbrella lib windowsapp.lib.

For "Windows 8.x" configurations of the GamePad class using XInput 1.4, you'll need xinput.lib.

For Windows 7 configurations, use xinput9_1_0.lib.

Content pipeline

To use the Visual Studio graphics assets tools in the build system, be sure to add them to your project.

Note: When adding .spritefont, .sdkmesh, or .xwb files to your Universal Windows Platform (UWP) or Xbox One project, you need to manually set the file properties to "Content: Yes" for all configurations to have these files included in your AppX package. .dds files, other image file formats, and .wav files are automatically detected as a media file and are included as content by default.

Error handling

DirectXTK makes use of C++ exception handling which should be enabled by the application via the /EHsc compiler switch. In Visual Studio, this is set in the project settings under "C++ / Code Generation" with Enable C++ Exceptions set to "Yes (/EHsc)" for all configurations.

Visual Studio Express editions have limited exception handling debugging support, so consider using VS Community or Pro+ instead.

Smart-pointers and reference counting

DirectXTK encourages and makes use of a number of smart-pointers to simplify resource lifetime tracking.

Additional information

Implementation

All content and source code for this package are subject to the terms of the MIT License.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

For Use

  • Universal Windows Platform apps
  • Windows desktop apps
  • Windows 11
  • Windows 10
  • Windows 8.1
  • Windows 7 Service Pack 1
  • Xbox One

For Development

  • Visual Studio 2022
  • Visual Studio 2019 (16.11)
  • clang/LLVM v12 - v16
  • MinGW 12.2, 13.2
  • CMake 3.20

Related Projects

DirectX Tool Kit for DirectX 12

DirectXMesh

DirectXTex

DirectXMath

Win2D

Tools

Test Suite

Model Viewer

Content Exporter

DxCapsViewer

Clone this wiki locally